CGI Applications and WebSTAR

This guide to writing CGI applications for WebSTAR should be usable for anyone, even if you have no previous programming experience. Of course, you shouldn't expect miracles (at least not here). These lessons will make things easier for most people, but they still require work and study. Take your time, think about what is said here, challenge anything that seems to be wrong (its not unthinkable that I get something wrong here) and do things in order as much as possible.

NOTE: This information is relevant only for WebSTAR (or MacHTTP 2.x) on Macintosh computers. While CGI applications exist for most platforms, the method of communication between CGI applications and the servers on various platforms differs so CGI applications cannot be used across platforms. There is one kind for Unix, another for Macintosh, and yet another for any other types of computers you might be using.

What does CGI mean?

CGI stands for "Common Gateway Interface". There. Now you know. The CGI definition provides a standard for external gateway programs to interface with information servers such as WebSTAR. When WebSTAR passes information off to a CGI application it not only sends the data from the user, but it also includes useful information about the transaction such as the client address, username, and password. You can read more about this in the Overview of CGI from NCSA.

How They Work - The Basics

When trying to understand how CGI applications work, the first thing to learn is the difference between the server and the client. WebSTAR is the server. Mosaic, MacWeb, and Netscape are all clients. When a user clicks on a link, the client send a request to the server to see the file that the link points to. Here's an example of some typical client-server interaction with an HTML page:

  Netscape: I want to look at the page with the URL 
            http://www.uwtc.washington.edu/UWHome.html
  
  WebSTAR: Ah!  That's one of my pages.  Here is all 
           the data from the URL you sent.  I'm sending 
           it as text.
  
  Netscape: Ah!  I see the text begins with an HTML tag 
            that I recognize.  I'll interpret this as HTML 
            then and display it correctly for my user.
  
  WebSTAR: I couldn't care less how you display it.  I'm 
           done dumping the data so goodbye.

As you can see, the client and the server both have their responsibilities in the interaction. The server decides what the client is requesting and how to feed it back to the client. The client decides what to do with what is returned to display it for the user.

When the user requests a URL that involves a CGI application (like clicking on a map, submitting a form, or many other things), the interaction is a little different because there is also interaction between the server and the CGI. Let's take a look now at the conversation that might occur between a server and client when handling a map click (assuming they speak English, of course).

  User: Hmmmm.  A map of Washington state.  There's a star in 
        the upper right-hand corner.  I wonder what that's 
        for.  Let's click on it.

  Netscape: Let's see, that click was at 287,48.  I'll add 
            that to the URL that was given with the map and 
            send it back to the server.

  WebSTAR: Hey, someone sent me a URL with some extra data. 
           That URL is for a CGI application on this machine. 
           Well I'll just send an Apple event to that CGI 
           application with the data enclosed in the post_args 
           argument.  I'm glad I don't have to do anything to 
           the data myself.

  CGI app: Finally, an Apple event!  Let's see, first I 
           decode the information in the post_args argument. 
           Now I can use these map click coordinates to figure 
           out what page to return to the client.  Here it is - 
           I'll send the server an Apple event reply, 
           containing the URL for the new page and a code to 
           redirect the client to that page.
  
  WebSTAR: Finally.  I've been waiting for this Apple event reply. 
           This code says I should redirect the client to this 
           other page instead.  I'll send back the new page then.
  
  Netscape: Here comes another HTML page.  Better display it 
            nicely for my user.
  
  User: Republic, Washington? I've never even heard of that
        place before!

Well, that was a bit long, but it should give you an idea of the complex interactions that go on when you're using a CGI application. There are a couple of important points to remember from the above nonsense:

The client is responsible for packaging data to be passed to the CGI application. With maps this is easy, but when you begin trying to do forms, there will be significant differences in how clients package the information from a form. Buy plenty of aspirin first.
The server generally does not do any processing of the actual data going to the CGI application or of pages being returned to the client. The server's only job is to handle connections, use the proper method to return pages and files, and handle communications between the client and CGI applications.
The CGI application is responsible for either returning a complete page, including HTTP header, or for returning a code to redirect to a new URL and the new URL. The server has no idea what is going on and will generate an error if the CGI fails to provide the needed information.
Apple events are used for communications between WebSTAR and outside applications. There is a special Apple event used for communicating with CGI applications. This Apple event contains quite a bit of information in addition to information passed by from the user, as defined by the CGI definition. Any application that can accept this Apple event and reply to it can be a CGI application.

Synchronicity

Not too long ago (back when it was known as MacHTTP) WebSTAR was only able to handle CGI applications synchronously. That meant that every time a CGI application was called, WebSTAR waited for a response. Therefore, noone else could get any information until that CGI application finished and returned some information. A very slow connection, sending lots of data to a slow application, could tie up your server for several minutes or cause an error when WebSTAR got tired of waiting.

Later, Chuck Shotton added the ability to run the CGI applications asynchronously. This meant that WebSTAR didn't have to wait uselessly while the CGI application ran. Instead, it passed an Apple event to the application then went on processing other things until a reply was received. To distinguish between the two, WebSTAR now recognizes two different file extensions. ".cgi" means the file should be handled synchronously and ".acgi" means to handle it asynchronously. The latter is almost always preferable, but a well-written CGI application can run either way. The key with asynchronous CGI's is to remember that Apple events might be queued up in your application while it is processing the current event. Therefore, you want to design the application so it doesn't quit immediately after processing an event or it might miss the next one. Instead, give it time to test to see if there is another event queued up.

How To Write a CGI Application

You can write a CGI application in any language you want. It only needs be able to accept and return the proper Apple event information. There are examples and shells available in C, Fortran, MacPerl, and Prograph, and you could even use an application like 4D, HyperCard, or SuperCard. However, for most of us, the easiest way to write a CGI application is by using AppleScript. Luckily for you, I have a tutorial on writing CGI applications using AppleScript.

Jon Wiederspan
Last Edited: April 26, 1995
Copyright Jon Wiederspan, 1994,1995